Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

17

3D Graphics Kit

Classes

N3DCamera

Inherits From:	View : Responder : Object

Initializing and Freeing

- init	Initializes with 0 frame size

- initFrame:(const NXRect *)fRect	Initializes with specified frame size

- free	Frees the N3DCamera

All Drawing

- (BOOL)lockFocus	YES if PostScript and RenderMan drawing lock on camera

- unlockFocus	Unlocks PostScript and RenderMan drawing

- drawSelf:(NXRect *)rects :(int)nRects	Performs all RIB and PostScript drawing

RenderMan Drawing

- render	Renders the camera and any content shapes

- renderSelf:(RtToken)context	Override to perform custom rendering in the camera

- setFlushRIB:(BOOL)flag	Sets the receiver to invoke flushRIB within render

- doesFlushRIB	Tests whether the receiver invokes flushRIB within render

- flushRIB	Waits until all RIB code has been rendered

PostScript Drawing

- drawPS:(NXRect *)rects :(int)nRects	Override to perform custom PostScript drawing

Background Color

- setBackgroundColor:(NXColor)color	Sets the NXColor filled behind all drawing

- (NXColor)backgroundColor	The NXColor filled behind all drawing 

- setDrawBackgroundColor:(BOOL)flag	If flag is YES, fills color behind all drawing

- (BOOL)doesDrawBackgroundColor	YES if camera fills color behind all drawing

PostScript Transformation Management

- setFrame:(const NXRect *)fRect	Sets frame for both PostScript and RenderMan coordinate systems

- moveTo:(NXCoord)x :(NXCoord)y	Moves both PostScript and RenderMan coordinate systems

- moveBy:(NXCoord)deltaX :(NXCoord)deltaY	Moves both PostScript and RenderMan coordinate systems

- sizeTo:(NXCoord)width :(NXCoord)height	Resizes both PostScript and RenderMan coordinate systems

- sizeBy:(NXCoord)deltaWidth 	Resizes both PostScript and RenderMan coordinate 
:(NXCoord)deltaHeight		systems

- rotateTo:(NXCoord)angle	Prevents rotation of PostScript coordinate system

- rotateBy:(NXCoord)deltaAngle	Prevents rotation of PostScript coordinate system

Shape Hierarchy Management

- setWorldShape:a3DShape	Sets world shape

- worldShape	Returns world shape 

Global Light Management

-addLight:aLight	Adds an N3DLight to the camera's global light list

- removeLight:aLight	Removes an N3DLight to the camera's global light list

- lightList	Returns the camera's global light list

Picking

- selectShapesIn:(const NXRect *)selectionRect	Returns a List of N3DShapes in selectionRect

Projection Rectangle

- setProjectionRectangle:(float)left 	Sets the 3D coordinate system projection rectangle
:(float)right 
:(float)top 
:(float)bottom

- getProjectionRectangle:(float *)left 	Returns the 3D coordinate system's projection
:(float *)right 		 rectangle
:(float *)top 
:(float *)bottom

Selecting Projection Type

- setProjection:(N3DProjectionType)aProjection	Sets the projection type

- (N3DProjectionType)projectionType	Returns the projection type

Pretransform Matrix

- setPreTransformMatrix:(RtMatrix)theMatrix	Sets the camera's pretransformation matrix

- getPreTransformMatrix:(RtMatrix)theMatrix	Returns the camera's pretransformation matrix

- setUsePreTransformMatrix:(BOOL)flag	Sets the camera to use its pretransformation matrix

- (BOOL)usesPreTransformMatrix	YES if camera uses its pretransformation matrix

Setting Viewpoint 

- setEyeAt:(RtPoint)fromPoint 	Sets the eye-to-viewpoint vector and roll
toward:(RtPoint)toPoint 
roll:(float)aRollAngle

- getEyeAt:(RtPoint *)fromPoint 	Gets the eye-to-viewpoint vector and roll
toward:(RtPoint *)toPoint 
roll:(float *)aRollAngle

- moveEyeBy:(float)sDistance 	Moves camera in its own coordinate system
:(float)tDistance 
:(float)uDistance

- rotateEyeBy:(float)dElev :(float)dAzim 	Rotates the camera in its own coordinates
about:(RtPoint)pivotPtr

Clipping Planes

- setClipPlanesNear:(float)aNearPlane 	Sets the camera's near and far clipping planes
far:(float)aFarPlane

- getClipPlanesNear:(float *)aNearPlane 	Returns the camera's near and far clipping planes
far:(float *)aFarPlane

Field of View

- setFieldOfViewByAngle:(float)viewAngle	Sets the viewing angle of the camera

- setFieldOfViewByFocalLength:(float)aLength	Converts a focal length into a viewing angle for the camera

- (float)fieldOfView	Returns the viewing angle of the camera

Pixel Aspect Ratio

- setPixelAspectRatio:(float)theRatio	Sets the pixel aspect ratio for the camera

- (float)pixelAspectRatio	Returns the pixel aspect ratio for the camera

Converting Coordinates

- convertPoints:(RtPoint *)points 	Converts an array of points to PostScript coordinates
count:(int)n 
fromSpace:aShape

- convertPoints:(NXPoint *)mcoords 	Converts PostScript points to world coordinates
count:(int)pointCount 
toWorld:(RtPoint *)wcoords

Crop Windows

- (int)numCropWindows	Count of rectangle divisions for photoreal rendering

- cropInRects:(NXRect *)theRects 	Returns rectangles representing horizontal strips of 
nRects:(int)rectCount		camera image

Frame Number

- (int)frameNumber	Returns 1

Printing

- (BOOL)canPrintRIB	Returns YES

Copying RIB

- copyRIBCode:(NXStream *)stream	Copies RIB code generated by the receiver

Setting World Attributes

- worldBegin:(RtToken)theContext	Calls RiWorldBegin()

- worldEnd:(RtToken)theContext	Calls RiWorldEnd()

Setting and Getting the Delegate

- setDelegate:cameraDelegate	Sets the receiver's delegate

- delegate	Returns the receiver's delegate

Setting the Hider

- (N3DHider)hider	Returns the receiver's N3DHider

- setHider:(N3DHider)cameraHider	Sets the receiver's N3DHider

- setSurfaceTypeForAll:(N3DSurfaceType)surface 
chooseHider:(BOOL)flag	Sets surface type for shapes in world shape hierarchy

Rendering Photorealistically

- (int)renderAsEPS	Begins rendering, returns identifier for rendering session 

- (int)renderAsTIFF	Begins rendering, returns identifier for rendering session 

Archiving

- read:(NXTypedStream *)theStream	Reads the camera from the stream

- write:(NXTypedStream *)theStream	Writes the camera to the stream

- awake	Performs additional initialization after unarchiving

Methods Implemented by the Delegate

- camera:theCamera 	Handles images generated by photoreal rendering 
didRenderStream:(NXStream *)imageStream 		methods
tag:(int)theJob 
frameNumber:(int)currentFrame

N3DContextManager

Inherits From:	Object

Initializing and Freeing

+ new	Returns (creating if necessary) one instance per application

- free	Destroys all contexts, frees the receiver

Getting the Main Context

- (RtToken)mainContext	Returns (creating if necessary) the application's main context

Creating Other Contexts

- (RtToken)createContext:(const char *)name	Creates a named context

- (RtToken)createContext:(const char *)name	Creates a named context for a specific renderer
withRenderer:(RtToken)renderer

- (RtToken)createContext:(const char *)came	Creates a named context on a file
toFile:(const char *)ribFile

- (RtToken)createContext:(const char *)name	Does nothing, returns NULL
toStream:(NXStream *)stream

Managing the Current Context

- (RtToken)currentContext	The application's current context

- (RtToken)setCurrentContext:(RtToken)context	Sets the current context, returns previous context

- (RtToken)setCurrentContextByName:(const char *)name
	Sets the current context by name, returns previous context

Destroying a Context

- (void)destroyContext:(RtToken)context	Destroys the context

- (void)destroyContextByName:(const char *)name
	Destroys a context with name

Archiving

- awake	Performs additional initialization after unarchiving

N3DLight

Inherits From:	N3DShape : Object

Initializing

- init	Initializes the receiver as an N3D_AmbientLight

Setting Light Type

- setType:(N3DLightType)aType	Sets the receiver's light type

- (N3DLightType)type	Returns the receiver's light type

- makeAmbientWithIntensity:(RtFloat)intensity	Sets type N3D_AmbientLight with appropriate parameter

- makePointFrom:(RtPoint)from 	Sets type N3D_PointLight with appropriate 
intensity:(RtFloat)intensity		parameters

- makeDistantFrom:(RtPoint)fromPoint	Sets type N3D_PointLight with appropriate
to:(RtPoint)toPoint 		 parameters
intensity:(RtFloat)i

- makeSpotFrom:(RtPoint)fromPoint 	Sets type N3D_SpotLight with appropriate parameters
to:(RtPoint)toPoint
coneAngle:(RtFloat)coneAngle 
coneDelta:(RtFloat)deltaAngle
beamDistribution:(RtFloat)distribution
intensity:(RtFloat)intensity

Setting Light Parameters

- setFrom:(RtPoint)fromPoint	Sets the from point

- setFrom:(RtPoint)fromPoint 	Sets the from and to points
to:(RtPoint)toPoint

- getFrom:(RtPoint *)fromPoint 	Returns the from and to points
to:(RtPoint *)toPoint

- setConeAngle:(RtFloat)coneAngle 	Sets the cone angle, cone delta, and beam distribution
coneDelta:(RtFloat)coneDelta 
beamDistribution:(RtFloat)distribution

- getConeAngle:(RtFloat *)coneAngle 	Gets the cone angle, cone delta, and beam distribution
coneDelta:(RtFloat *)coneDelta 
beamDistribution:(RtFloat *)distribution

- setIntensity:(RtFloat)intensity	Sets the intensity

- (RtFloat)intensity	Returns the intensity

Rendering

- renderSelf:(N3DCamera *)theCamera	Renders the light as a local light

- renderGlobal:(N3DCamera *)theCamera	Renders the light as a global light

Global Light Management

- setGlobal:(BOOL)flag	Override to add behavior on becoming/resigning global

- (BOOL)isGlobal	YES if light is global

Switching On and Off

- switchLight:(BOOL)flag	If flag is YES, turns receiver on

Setting Color

- setColor:(NXColor)theColor	Sets the receiver's color

- (NXColor)color	Returns the receiver's color

Archiving

- read:(NXTypedStream *)theStream	Reads the receiver from the stream

- write:(NXTypedStream *)theStream	Writes the receiver to the stream

- awake	Performs additional initialization after unarchiving

N3DMovieCamera

Inherits From:	N3DCamera : View : Responder : Object

Initializing

- initFrame:(const NXRect *)fRect	Initializes the receiver

RenderMan Drawing

- render	Renders current frame; if printing, renders current page

Interactive Display

- displayMovie	Displays movie, first frame to last, onscreen

Frame Numbers

- setFrameNumber:(int)aFrameNumber	Sets the current frame number

- (int)frameNumber	Returns the current frame number

- setStartFrame:(int)start 	Sets counters for movie
endFrame:(int)end 
incrementFramesBy:(int)skip

- (int)startFrame	Returns the first frame number

- (int)endFrame	Returns the last frame number

- (int)frameIncrement	Returns the frame increment

Archiving

- read:(NXTypedStream *)theStream	Reads the receiver from the stream

- write:(NXTypedStream *)theStream	Writes the receiver to the stream

- awake	Performs additional initialization after unarchiving

N3DRenderPanel

Inherits From:	Panel : Window : Responder : Object

Initializing the Class

+ initialize	Initializes the class with data from the defaults database

+ new	Creates, if necessary, and returns an N3DRenderPanel

Setting Accessory View

- accessoryView	Returns the accessory view

- setAccessoryView:aView	Sets the accessory view

Running Modal

- (int)runModal	Presents the render panel in a model loop

Resolution

- (int)resolution	Returns the resolution set by the user in the panel

Host Management

- (int)numSelectedHosts	Returns the number of hosts selected by the user

- (char **)hostNames	Returns an array of strings for selected host names

Browser Delegate Method

- (int)browser:sender	Fills the panel's browser with host names
fillMatrix:theMatrix
inColumn:(int)col

N3DRIBImageRep

Inherits From:	NXImageRep : Object

Initializing and Freeing

- initFromFile:(const char *)ribfile	Initializes the receiver from a file

- initFromStream:(NXStream *)ribStream	Initializes the receiver from a stream

- free	Frees the receiver

Declaring Data Types

+ (const char *const *)imageUnfilteredFileTypes	Returns supported file types

+ (const NXAtom *)imageUnfilteredPasteboardTypes
	Returns supported pasteboard types

+ (BOOL)canLoadFromStream:(NXStream *)theStream
	Tests theStream for RIB data

Drawing

- (BOOL)drawAt:(const NXPoint *)point	Returns YES if the image is successfully drawn at point

- (BOOL)drawIn:(const NXRect *)rect	Returns YES if the image is successfully drawn in rect

- (BOOL)draw	Returns YES if the image is successfully drawn

Size

- getBoundingBox:(NXRect *)rectangle	Returns the rectangle that bounds the image

- getSize:(NXSize *)theSize	Returns the size of the image

Background Color

- (NXColor)backgroundColor	Returns the background color

- setBackgroundColor:(NXColor)theColor	Sets the background color

Hidden Surface Removal Type

- (N3DHider)hider	Returns the hider type for rendering images

- setHider:(N3DHider)theHider	Sets the hider type for rendering images

Surface Type

- setSurfaceType:(N3DSurfaceType)type	Sets the surface type used for rendering images

- (N3DSurfaceType)surfaceType	Returns the surface type used for rendering images

Archiving

- read:(NXTypedStream *)theStream	Reads the receiver from the stream

- write:(NXTypedStream *)theStream	Writes the receiver to the stream

N3DRotator

Inherits From:	Object

Initializing

- init	Initializes the receiver

- initWithCamera:myCamera	Initializes the receiver and sets its camera

Setting Parameters

- setCamera:myCamera	Sets the receiver's camera

- setCenter:(const NXPoint *)center 	Sets the receiver's center point and radius
andRadius:(float)radius

Axes of Rotation

- setRotationAxis:(N3DAxis)axis	Sets the axes about which the receiver rotates

- (N3DAxis)rotationAxis	Returns the axis about which the receiver rotates

Mouse Tracking

- trackMouseFrom:(const NXPoint *)lastPoint	Accepts two points in camera coordinates, returns
to:(const NXPoint *)thisPoint 		rotations based on their offset
rotationMatrix:(RtMatrix)theRotation
andInverse:(RtMatrix)theInverse

Archiving

- read:(NXTypedStream *)theStream	Reads the receiver from the stream

- write:(NXTypedStream *)theStream	Writes the receiver to the stream

N3DShader

Inherits From:	Object

Initializing and Freeing 

- init	Initializes the receiver with no shader file

- initWithShader:(const char *)aShader	Initializes the receiver with a shader file

- free	Frees the receiver

Shader Language Object File

- setShader:(const char *)aShader	Sets the receiver's shader

- (const char *)shader	Returns the receiver's shader

Shader Color

- setColor:(NXColor)aColor	Sets the receiver's color

- (NXColor)color	Returns the receiver's color

- setUseColor:(BOOL)flag	Sets the receiver to apply its color

- (BOOL)doesUseColor	YES if receiver applies color

Shader Transparency

- setTransparency:(float)alphaValue	Sets the receiver's transparency

- (float)transparency	Returns the receiver's transparency

Shader Function Argument Handling

- (int)shaderArgCount	The number of arguments for the shader function

- (const char *)shaderArgNameAt:(int)argIndex	The name of the indicated argument

- (SLO_TYPE)shaderArgType:(const char *)argName
	The type of the named argument

- (BOOL)isShaderArg:(const char *)argName	YES if argName is an argument to the shader function

- setShaderArg:(const char *)floatName 	Sets the specified argument to the specified value
floatValue:(float)floatValue

- setShaderArg:(const char *)stringName 	Sets the specified argument to the specified value
stringValue:(const char *)stringValue

- setShaderArg:(const char *)pointName 	Sets the specified argument to the specified value
pointValue:(RtPoint)pointValue

- setShaderArg:(const char *)colorName 	Sets the specified argument to the specified value
colorValue:(NXColor)colorValue

- getShaderArg:(const char *)floatName 	Gets the specified value for the specified argument
floatValue:(float *)floatValue

- getShaderArg:(const char *)stringName 	Gets the specified value for the specified argument
stringValue:(const char **)stringValue

- getShaderArg:(const char *)pointName 	Gets the specified value for the specified argument
pointValue:(RtPoint *)pointValue

- getShaderArg:(const char *)colorName 	Gets the specified value for the specified argument
colorValue:(NXColor *)colorValue

- resetShaderArg:(const char *)argName	Resets the specified argument to its default value

Shader Type

- (SLO_TYPE)shaderType	Returns the type of the shader

Setting

- set	Applies the shader function during rendering

Archiving

- read:(NXTypedStream *)theStream	Reads the receiver from the stream

- write:(NXTypedStream *)theStream	Writes the receiver to the stream

N3DShape

Inherits From:	Object

Initializing and Freeing

- init	Initializes and returns the receiver

- free	Frees the receiver and its descendants

- freeAll	Frees the receiver, its next peer and its descendants

Rendering the N3DShape

-render:(N3DCamera *)theCamera	Renders the shape and its descendants

- renderSelf:(N3DCamera *)theCamera	Override to implement actual rendering

- renderSelfAsBox:(N3DCamera *)theCamera	Renders only the shape's bounding box

Traversing the Shape Hierarchy

- nextPeer	Returns the shape ªto the rightº

- previousPeer	Returns the shape ªto the leftº 

- firstPeer	Returns the shape ªto the far leftº of receiver's peer group

- lastPeer	Returns the shape ªto the far rightº of receiver's peer group

- descendant	Returns the shape ªbelowº the receiver

- lastDescendant	Returns the farthest descendant below the receiver

- ancestor	Returns the shape ªabove the receiver

- firstAncestor	Returns the shape at the top of the receiver's hierarchy

- (BOOL)isWorld	YES if the receiver is at the top of its hierarchy

Managing the Shape Hierarchy

- linkPeer:aPeer	Inserts aPeer between receiver and its next peer

- linkDescendant:aDescendant	Inserts aDescendant between receiver and its descendant

- linkAncestor:anAncestor	Sets receiver's ancestor, returns previous ancestor

- unlink	Unlinks the receiver, reconnects peers and descendants

- group:anAncestor	Makes the receiver a descendant of anAncestor

- ungroup	Removes receiver from hierarchy, promotes descendant

Shader

- setShader:aShader	Sets an N3DShader for the shape

- shaderType:(SLO_TYPE)type	Returns the N3DShader of type 

Surface

- (N3DSurfaceType)surfaceType	Returns the receiver's surface type

- setSurfaceType:(N3DSurfaceType)theSurface	Sets receiver's surface type; if flag is YES, sets descendants 
andDescendants:(BOOL)flag	surface types

Bounding Box

- getBoundingBox:(RtBound *)boundingBox	Returns by reference the receiver's bounding box

- setDrawAsBox:(BOOL)flag	Sets the receiver to draw only its bounding box

- (BOOL)doesDrawAsBox	YES if the receiver draws only its bounding box

- getBounds:(NXRect *)boundingRect 	Returns the rectangle representing the receiver's 
inCamera:theCamera		bounding box in the coordinates of the camera

Converting Points 

- convertObjectPoints:(RtPoint *)points 	Converts points from the receiver's coordinate system
count:(int)n 		to that of camera
toCamera:camera

- convertPoints:(RtPoint *)points 	Converts points from an ancestor's coordinate system
count:(int)n 		to that of the receiver
fromAncestor:(N3DShape *)theShape

- convertPoints:(RtPoint *)points 	Converts points from the receiver's coordinate system
count:(int)n 		to that of an ancestor
toAncestor:(N3DShape *)theShape

Selectability

- setSelectable:(BOOL)flag	Sets whether the receiver can be selected

- (BOOL)isSelectable	YES if the receiver can be selected

Visibility

- setVisible:(BOOL)flag	Sets the receiver to render when renderSelf: is invoked

- (BOOL)isVisible	YES if receiver renders when renderSelf: is invoked

Naming Shapes

- setShapeName:(const char *)aName	Sets the name of the shape

- (const char *)shapeName	Returns the name of the shape

Delegate for Rendering

- setRenderDelegate:aShape	Sets the rendering delegate for the receiver

- removeRenderDelegate	Removes and returns the render delegate

- renderDelegate	Returns the render delegate

Transformation Matrices 

- setTransformMatrix:(RtMatrix)newTransform
	Sets the receiver's transformation matrix

- getTransformMatrix:(RtMatrix)transform	Returns the receiver's transformation matrix

- concatTransformMatrix:(RtMatrix)theMatrix	Multiplies the transform matrix with theMatrix,
premultiply:(BOOL)flag		premultiplying by theMatrix if flag is YES

- getCompositeTransformMatrix:(RtMatrix)theMatrix 
relativeToAncestor:(N3DShape *)theAncestor
	Returns the matrix representing the transformation between theAncestor's space and the receiver's

- getInverseCompositeTransformMatrix:(RtMatrix)theMatrix 
relativeToAncestor:(N3DShape *)theAncestor
	Returns the matrix representing the transformation between the receiver's space and theAncestor's

Rotation, Scaling, Translation

- rotateAngle:(float)ang 	Rotates the receiver about its origin and the point
axis:(RtPoint)referencePoint

- preRotateAngle:(float)angle 	Premultiplies the rotation of the receiver about its 
axis:(RtPoint)referencePoint		origin and the point

- scale:(float)xScaleFactor 	Scales the receiver 
:(float)yScaleFactor 
:(float)zScaleFactor

- prescale:(float)xScaleFactor 	Scales the receiver, premultiplying the transformation 
:(float)yScaleFactor 
:(float)zScaleFactor

- scaleUniformly:(float)scaleFactor	Scales the receiver uniformly in all axes

- prescaleUniformly:(float)scaleFactor	Scales the receiver uniformly in all axes, premuliplying the transformation

- translate:(float)xTranslation 	Translates the receiver
:(float)yTranslation 
:(float)zTranslation

- pretranslate:(float)xTranslation 	Translates the receiver, premultiplying the 
:(float)yTranslation 	transformation
:(float)zTranslation

Archiving

- read:(NXTypedStream *)theStream	Reads the camera from the stream

- write:(NXTypedStream *)theStream	Writes the camera to the stream

- awake	Performs additional initialization after unarchiving